Libris Britannia 4

home *** CD-ROM | disk | FTP | other *** search

/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / ASSEMBLE / H055.ZIP / DOC / SYSTEM.DOC < prev next >

Wrap

Text File | 1988-01-05 | 30KB | 635 lines

SYSTEM.DOC PC/370 release 4.1 system services documentation Chapter table of contents: 1. Introduction 2. File input and output services 3. Program load and execution services 4. SVC documentation in SVC # order 4. Floating point system documentation ********* Chapter 1. Introduction ********* The PC/370 system supports a number of supervisor services through the standard 370 SVC interface. In supervisor state, each SVC invokes pseudo microcode which performs the function requested at native processor speed. In problem state each SVC causes a standard SVC interrupt storing the current PSW at location X'20' and loading the new PSW from location X'60'. Supervisor call routines can be user written to map any SVC into any desired function in problem state. In supervisor state, svc's 1-7 provide a set of input and output facilities using MS-DOS file handle I/O and an extended data control block defined by the user which allows access to sequential and random files. Svc's 10-11 provide virtual memory dynamic management. In addition to the other misc. functions provided, svc 34 provides a general purpose interrupt interface which can be used to map PC/370 area into PC registers and issue any MS-DOS function call or BIOS interrupt. Svc's 128-191 map into BIOS interrupts using simple register to register mapping. Svc's 200-241 map into MS-DOS function calls 0-41 using simple register to register mapping. Note function calls above 41 can be issued using svc 34 interface which is the preferred method for future releases. ********* Chapter 2. File input and output services ********* The PC/370 supervisor calls to the I/O supervisor all require register 2 to point to the DCB. The SVC's are as follows: SVC FUNCTION OPTIONS 1 OPEN 2 CLOSE 3 READ register 1 must be address of block or zero 4 WRITE register 1 must be address of block or zero 5 GET register 1 must be address of area or zero 6 PUT register 1 must be address of area or zero 7 DELETE 8 SEARCH 23 RENAME The PC/370 system supports sequential and random access to files using MS-DOS file handle I/O with directory pathing. To access a file, a data control block (DCB) must be defined in the program with fields defined as shown in the dummy section (DSECT) called IHADCB found in CPY\IHADCB.CPY and demonstrated in UTIL\PRINTDOC.ALC. All fields must be defined prior to open and cannot be changed while the file is open with the exception of RCD, BUF, and RBA as described below. An explanation of each field in the DCB follows: 1. DCBDCB - DCB identifier consisting of the four EBCDIC characters ADCB. These characters are verified each time an I/O routine is called with the address of the DCB in register 2. An attempt is made to exit to the synchronous error exit address if there is no match. 2. DCBDSN - address of up to 64 character EBCDIC path and file name followed by a zero byte. This field is automatically translated to ASCII as required. 3. DCBFID - MS-DOS assigned file handle at open time. This field must be initialized to high values or open routine will assume file is already open and take SYNAD exit. 4. DCBFLG - file condition flags used by I/O routines. This field must be initialized to zero except user defined buffer bit DFUBUF and user requested ASCII file conversion bit DFTRAN may be turned on. No other bits may be modified by user. If the DFTRAN (X'08') bit is set, input records are translated to EBCDIC in the record area. Output records are translated to ASCII in the record area, written, and then translated back to EBCDIC. The entire LRECL area is translated. For text mode, each record must end with EBCDIC line feed. 5. DSORG - data set organization EBCDIC code: S for sequential R for random file access. 6. MACRF - data set access EBCDIC code: R for read block with length of BLKSZ W for write block with length of BLKSZ (note PRECL can override BLKSZ on write) G for get logical record into RCD area P for put logical record form RCD area 7. RECFM - data set record format EBCDIC code: F - fixed length records with length LRECL for get/put sequential access or length BLKSZ for read/write random or sequential access. V - variable length records with length stored in first 2 bytes (valid lengths range from 3 to 64k). Maximum length allowed for a file is LRECL and only sequential get/put modes supported. T - text records ending with end of record code (EOR usually X'0A' line feed). Maximum length allowed for a file is LRECL and only sequential get/put modes supported. 8. EOR - end of record code for text (default NL X'0A') 9. EOF - end of file code for text (default X'1A') 10. LRECL - length of logical record. Maximum is 64K less 17 bytes. Minimum is 3 for RECFM=V, 2 for RECFM=T or 1 for RECFM=F. 11. BLKSZ - length of block. Maximum is 64K less 17 bytes and minimum is 3. If zero is specified, a default block of 8k will be dynamically allocated and deallocated at open and close respectively. BLKSZ should be specified for read/write access. For sequential access, larger block size reduces contention between multiple files by reading or writing entire blocks at one time rather than for each record. If insufficient memory is available, the maximum available will be allocated. 12. EODAD - end of file exit address. This cannot be changed while file is open. 13. SYNAD - synchronous error exit. This cannot be changed while file is open. If register 2 does not point to a valid DCBDCB ID field not exit is taken and interactive debug is invoked. If exit is taken, register 0 contains error code and register 1 contains function code which can be used by to produce error message by calling subroutine LIB\SYNERROR.ALC which is in the default system relocatable library L370.LIB. 14. RCD - record area address for get/put only. This address may be changed on each get or put by placing new address in register 1. If register 1 contains zero, then current DCB area will be used. 15. BLK - block area address used for direct I/O via MS- DOS. If DFUBUF is not set at open, this area is dynamically allocated and deallocated using BLKSZ or default for length. If DFUBUF is set, then new block address can be set for each read or write by placing new address in register 1. If register 1 contains zero, then current DCB block will be used. 16. RBA - relative byte address for random access read/write. First byte of file is zero. This field must be reset for each random read or write. 17. REN - address of file rename followed by zero. Only used by RENAME SVC. Both DCBDSN and REN must be initialized in a closed DCB prior to RENAME SVC 23. 18. IOCNT - physical I/O count since open. Larger BLKSZ will reduce physical I/O count for sequential file access. 19. PRECL - physical record length on last read or write. This field is initialized to zero at open. On write, BLKSZ will be calculated if this field is zero, else this field will override length allowing short blocks to be written. This is useful in processing files of unknown length with fixed block logic. The last block read may be short, and the corresponding last block written may be short. Do not modify the reserved areas which are only used by PC/370 IOS while file is open. See UTIL\PRINTDOC.ALC for example of file access method. ********* Chapter 3. Program load and execution services ********* SVC FUNCTION OPTIONS 15 USEREXIT Transfer control to native code user exit at relative address in reg 15 via far call 25 LOAD Reg 1 points to ASCIIZ path/filename on return, reg 0 has file address, reg 1 has length 26 ATTACH Reg 0 must have file address of COM file and reg 1 must have desired length of attached addr. space 27 DETACH If in attached address space, exit to next instruction after attach in mother address space else exit to MS-DOS 36 RELOAD Reload file int memory at location in reg 0. Reg 1 must have file address and reg 15 must have maximum length of file allowed to be loaded into preallocated area. The PC/370 system includes support for dynamic loading and execution of 370 modules assembled and linked by A370.EXE and L370.EXE. Any file including COM and MOD type files can be loaded into free memory by use of the LOAD SVC 25. The only argument required is the address of the path and file name in register 1. The file name must end with a suffix of the form .XXX or a zero byte. The largest free memory area will be allocated and the file loaded into it. Register 0 will be set to the address of the area, and register 1 will be set to the length of the file. The unused portion of the allocated area will be freed. If the load operation was successful, register 15 will be set to zero, else it will be set to 1. Demo test program DEMOSVC.ALC illustrates the use of the load function to load an 8086 assembly language subroutine and execute it via user exit SVC 15. Any 370 COM file created by L370.EXE and loaded via the load SVC 25 above, can be executed it its own address space via the attach SVC 26. Register 0 must be set to point to the COM file (set by load SVC 25) and register 1 must be set to address space size (minimum set by load SVC 25), If additional space is to be included in the attached address space for dynamic use via GETMAIN/FREEMAIN SVC's 10/11, then the area to be added must be allocated in the mother address space prior to issuing attach SVC 26 and the total length of the COM file plus the allocated free space placed in register 1. A COM file can be executed multiple times via attach by reloading registers 0 and 1 and reissuing SVC 26. On second and following calls, the same address space control block built on the first call in the COM prefix area is reused (See CPY\IHASCB.CPY for layout) since it overlays original COM prefix data. Execution of the attached address space can be terminated via a detach SVC 27 which restores the mother address space and continues execution at the next instruction following the attach SVC 26. The only other way to terminate the attached address space normally is to issue an exit SVC 0 which exits directly to MS-DOS. A detach SVC 27 in an address space which has no mother, will cause exit to MS-DOS. An alternative to using attach/detach to execute dynamically loaded 370 code is to use simple branch and link. For 370 code linked into COM file, the 370 code starts X'210' from the beginning of the COM file. For code linked into MOD type file by L370.EXE using option M, the 370 code starts immediately at the beginning of the file (i.e. the file load address returned in register 0 by load SVC 25). For example of each type program loading and execution, see DEMO\MVS.ALC and DEMO\DEMOPSW.ALC demo programs. The virtual address space established for the execution of COM files created by L370.EXE has the following memory layout. For a sample DSECT of the address space control block, see CPY\IHASCB.CPY. 000 INITIAL PROGRAM LOAD PSW 008 INITIAL PROGRAM LOAD CCW1 010 INITIAL PROGRAM LOAD CCW2 018 EXTERNAL OLD PSW 020 SUPERVISOR CALL OLD PSW 028 PROGRAM OLD PSW 030 MACHINE CHECK OLD PSW 038 INPUT/OUTPUT OLD PSW 040 CHANNEL STATUS WORD 048 CHANNEL ADDRESS WORD 050 INTERVAL TIMER 058 EXTERNAL NEW PSW 060 SUPERVISOR CALL NEW PSW 068 PROGRAM NEW PSW 070 MACHINE CHECK NEW PSW 078 INPUT/OUTPUT NEW PSW 080 MVS PARM AREA POINTED TO BY REGISTER 1 AT ENTRY (A,H,EBCDIC TEXT) 100 SVC ATTACH INSTRUCTION 102 SVC DETACH INSTRUCTION POINTED TO BY REG 14 AT ENTRY 104 ADDRESS SPACE CONTROL BLOCK ASCB FOR CURRENT COM PROGRAM 124 RESERVED 138 SAVE AREA POINTED TO BY REG 13 AT ENTRY 180 PC/370 PACKAGE IDENTIFICATION RECORD 200 BEGINNING OF 370 CODE AND DEFAULT ENTRY POINTED TO BY REG 15 AT ENTRY IF NO OTHER ENTRY POINT SPECIFIED ON ALC END STATEMENT. ********* Chapter 4. All PC/370 supervisor services in SVC order ********* SVC FUNCTION REGISTERS input/output 0 exit to MS-DOS none 1 open file reg 2 = DCB address (see I/O section documentation) 2 close file reg 2 = DCB address 3 read block reg 2 = DCB, reg 1 must be address of block or zero 4 write block reg 2 = DCB, reg 1 must be address of block or zero 5 get record reg 2 = DCB, reg 1 must be address of area or zero 6 put record reg 2 = DCB, reg 1 must be address of area or zero 7 delete file reg 2 = DCB address 8 search file reg 2 = DCB address /reg 0 = return code 0 if found 9 program trace 3 character trace ID follows SVC 10 get memory reg 1 = length /reg 2 = address, reg 0 = 0 if ok if reg 0 > 0, then reg 1 = maximum memory available 11 free memory reg 1 = length and reg 2 = address /reg 0 = 0 if ok 12 ASCII to EBCDIC reg 1 = address and reg 2 = length 13 EBCDIC to ASCII reg 1 = address and reg 2 = length 14 set SPIE if reg 1 = 0, remove SPIE else set SPIE exit to reg 1 at SPIE entry, reg 0 contains instruction length in high 16 bits, interruption code in low 16 bits, reg 1 contains interruption address, and reg 2 contains program interruption element block (see CPY\IHAPIE.CPY). 15 user exit reg 15 = entry point to COM 80x86 code via far call 16 instr. count /reg 1 = current 370 instruction count 17 load user exit reg 1 = ASCIIZ path/file name /reg 0=addr.reg 1=len. 18 time of date /reg 0 = hour, minute, second, 100th second, reg 1 = year, reg 2 = day, month, day of week 19 allocate memory reg 1 = address of MS-DOS real block, reg 2 = length /if reg 0 not zero, then reg 2 = max. available 20 deallocate mem. reg 1 = address of MS-DOS real block 21 input byte reg 1 = device address, reg 0 = byte 22 output byte reg 1 = device, reg 0 = byte 23 rename file reg 2 = DCB address 24 display line reg 1 = attributes, reg 2 = address, reg 15 = row/col 25 load file reg 1 = path/filename /reg 0 = address, reg 1 = length 26 attach program reg 0 = COM file address, reg 1 = address space length 27 detach program none (return to instruction after attach) 28 svc 209 EBCDIC set EBCDIC to ASCII trans. for WTO svc 209 (default) 29 svc 209 ASCII turn off EBCDIC to ASCII translation 30 svc 209 CR turn on carriage return and line feed (default) 31 svc 209 no CR turn off carriage return and line feed 32 VA to SEG:OFF convert virtual address in R1 to segment:offset in R0 33 SEG:OFF to VA convert segment:offset in R0 to virtual address in R1 34 interrupt general purpose interrupt facility which supports all MS-DOS and BIOS interrupts using PC register vector table pointed to by R1 must be defined as follows (see CPY\IHAPCB.CPY): 0 PCVT DC C'PCVT' ID REQUIRED BY SVC 34 4 PCIN DS H INTERRUPT # (0-255) 6 PCPF DS H PF FLAGS REGISTER 8 PCAX DS H AX 10 PCBX DS H BX 12 PCCX DS H CX 14 PCDX DS H DX 16 PCDS DS H DS 18 PCSI DS H SI 20 PCES DS H ES 22 PCDI DS H DI PC registers are loaded from PCVT for interrupt. PC register results are also stored in PCVT area immediately after interrupt. Note segment:offset addresses such as DS:DX, DS:SI, or ES:DI required by interrupts can be calculated via SVC 32. Likewise returned segment:offset results can be translated back to PC/370 virtual addresses via SVC 33. This is a very powerful and therefore dangerous instruction. SVC's 128-191 and SVC's 200-241 should be used in place of this more general SVC when possible since they are a little faster (they don't load and store all PC registers and don't require PCVT setup). They are also much safer since an error in PCVT setup could invoke wrong interrupt or pass bad registers to any function including reboot interrupt, write to disk, etc SVC 34 does verify PCVT identifier and range of PCIN within 0-255. If verify fails, program interruption 19 occurs. If carry bit is set by interrupt, condition code 3 is set, else condition code 0 is set. 35 80x87 assist Scientific subroutine function assist via 80x87. Register 1 contains function # and values are passed via floating point registers. See chapter on floating point for more information. 36 RELOAD Load file into memory at address in reg 0. Reg 1 must have file address and reg 15 must have maximum file length allowed to be loaded in preallocated area. 37 SVCTRAP Define svc trap table via register 1 which contains address of user exit routine to be used with each svc. If register 1 is zero current svc trap table is cancelled. After table is defined, each svc call functions as follows: 1. If table+4*(svc #) contains zero, execute real PC/370 svc normally. 2. If svc trap active mode is set, execute real PC/370 svc normally. 3. If table+4*(svc #) is not zero, store current psw at old svc psw x'20', set trap active mode, and branch to trap exit address in table entry. LPSW instruction will always reset trap active mode, and normal exit from trap is via LPSW OLDSVC. All svc calls within trap routine including the svc which invoked trap will process as real svcs normally without storing psw. See DEMO\ DEMOTRAP.ALC program for examples. 128 - 191 issue BIOS interrupt number = svc # - X'80' with PC registers mapped as follows before and after interrupt: AX - low bytes of register 0 BX - low bytes of register 1 CX - low bytes of register 14 DX - low bytes of register 15 If carry set by call, then CC =3 else CC = 0. 8086 flags returned in high bytes of R0. 200 - 241 issue interrupt 21H with PC registers mapped as follows: For all svc's 200-241: AH - MS-DOS function call number = svc number -200 AL - low byte of register 0 BX - low bytes of register 1 for svc # 201-208, 211, 213, 214, and 225: DL - low byte register 2 for svc 209, 210, 212, and 215-241: DS:DS - segment:offset from virtual address in register 2 CX - returned in register 14 DX - returned in register 15 One of the most frequently used SVC's is 209 (write to operator). For example, to print message on standard output device via MS-DOS function call 9, the following 2 PC/370 instructions can be used: LA R2,=C'THIS IS A DEMO WTO MESSAGE$' SVC 209 The above example will print message on console and issue carriage return and line feed following message ending with $. To turn off automatic carriage return and line feed, issue SVC 31 prior to SVC 209. To eliminate overhead of converting from default EBCDIC strings to ASCII for 209, issue SVC 29 prior to SVC 209 and use PC/370 assembler extension for ASCII strings in double quotes. For example, this is the most efficient method of issuing messages: SVC 29 TURN OFF EBCDIC TO ASCII CONVERSION FOR 209 . . LA R2,=C"THIS IS A DEMO WTO MESSAGE$" SVC 209 ********* Chapter 5. Floating Point System Documentation ********* A. Introduction PC/370 release 4.0 contains support for the entire 370 floating point instruction set using the Intel 80x87 co-processor. If the co-processor is not installed, all floating point instructions cause operation exceptions as they would on a 370 without the floating point option. There is a new option in the L370 linkage editor (option P) which can be used to force turning off floating point option even when co-processor is installed. Default is to support floating point if it is installed and 370 module has been linked using release 3.0+ linkage editor. In addition to the standard floating point instructions, two additional levels of support have been added. Section F describes a set of SVC's which invoke extended microcode functions on the 80x87 chip such as square root, logs, etc. These SVC's are fast but most require special scaling of arguments. DOC\USER.DOC describes a set of scientific subroutines written in ALC which can be called to efficiently calculate functions over extended range of real numbers. B. Data formats The Intel 80x87 actually only supports one IEEE floating point format which has 64 bit mantissa and exponent range of 10**4932 which exceeds both the 370 short and long (double precision) formats of 24 and 56 bit mantissa's. Therefore, both the short and long operations are done with extra precision. The 370 extended format instructions are all supported but the precision actually available is only 64 bits versus the 112 on a 370. When short and long numbers are loaded into the 80x87, they are padded with zeros to the 64 bit length required. When an extended number is loaded into the 80x87, the last 8 bits are obtained from the second register in the specified extended register pair. The PC/370 cross assembler now supports E, D, and L data formats when the 80x87 is installed. C. Data exceptions The standard 370 exponent overflow, exponent underflow, and floating point divide exceptions are all supported. The program mask can be set to control whether program exception is allowed. One deviation from standard 370 convention, is to return the maximum floating point number with correct sign when overflow occurs instead of an invalid number. This is consistent with IEEE standard. D. Floating point instructions 1. Note that all operations are normalized using 80x87 and that the 370 unnormalized function identical to normalized instructions. 2. Compare short and long include all 64 bits in comparison. To round number to specific number of bits in short or long format, use the LRER or LRDR instruction prior to compare. E. Interactive debug facilities for floating point 1. When floating point support is active (i.e. option P is on and the 80x87 co-processor is installed), the R command will display third line with floating point register contents in hex. Note that the actual floating point register areas in memory are stored in 80x87 temporary real format to allow register to register instructions to execute faster since no conversion from or to 370 format is required. F. Extended 80x87 microcoded arithmetic functions The following extended arithmetic floating point functions are supported via SVC 35 with the function number in register 1. Arguments and results are in the floating point registers F0 and F2. # Formula: Notes: 1. F0 = LOG10(2) constant 2. F0 = LOGE(2) constant 3. F0 = LOG2(E) constant 4. F0 = LOG2(10) constant 5. F0 = PI constant 3.14159.... 6. F0 = ARCTAN(F2/F0) 0 <= F2 <= F0 < IFI (infinity) 7. F2/F0 = TAN(F0) 0 <= F0 <= PI/4 (sets F0 and F2) 8. F0 = SQRT(F0) 0 <= F0 < IFI 9. F0 = F2 * LOG2(F0) 0 < F0 < IFI, -IFI < F2 < IFI 10. F0 = F2 * LOG2(F0+1) 0 <= F0 < (1-(SQRT(2)/2)), _IFI < F2 < IFI 11. F0 = 2**F0 -IFI < F0 < IFI (note 1) 12. F0 = R0 convert to real 13. R0 = F0 convert to integer 14. F0 = MOD(F0/F2) return fraction of F0 mod F2 in F0 (note 2) 15. F0 = SIN(F0) argument may be any real radian value (note 3) 16. F0 = COS(F0) argument may be any real radian value (note 3) 17. F0 = TAN(F0) argument may be any real radian value (note 3) Notes: 1. This function uses equivalence expression to derive 2**F0 for all values of F0 rather than just the 0.0-0.5 range supported via the F2XM1 80x87 instruction. 2. Note this uses FPREM 80x87 instruction repeatedly to calculate exact remainder via successive subtraction. 3. Note 15-17 perform scaling of argument via FPREM 80x87 instruction and use FPTAN 80x87 instruction to derive tangent, sine and cosine. Register 15 is set to one of the following values at exit from svc: hex 00 - no errors detected 80 - 80x87 not operational 40 - invalid function number in register 1 20 - 80x87 precision error (inexact result such as 1/3 etc.) 10 - 80x87 underflow error (zero returned) 08 - 80x87 overflow error (max 370 value returned) 04 - 80x87 zero divide (max 370 value returned) 02 - 80x87 denormalized operand error (should not occur) 01 - 80x87 invalid operation error (should not occur)